<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html
    PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<!-- /fasttmp/mkdist-qt-4.3.5-1211793125/qtopia-core-opensource-src-4.3.5/tools/qdbus/src/qdbuscontext.cpp -->
<head>
  <title>Qt 4.3: QDBusContext Class Reference</title>
  <link href="classic.css" rel="stylesheet" type="text/css" />
</head>
<body>
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td align="left" valign="top" width="32"><a href="http://www.trolltech.com/products/qt"><img src="images/qt-logo.png" align="left" width="32" height="32" border="0" /></a></td>
<td width="1">&nbsp;&nbsp;</td><td class="postheader" valign="center"><a href="index.html"><font color="#004faf">Home</font></a>&nbsp;&middot; <a href="classes.html"><font color="#004faf">All&nbsp;Classes</font></a>&nbsp;&middot; <a href="mainclasses.html"><font color="#004faf">Main&nbsp;Classes</font></a>&nbsp;&middot; <a href="groups.html"><font color="#004faf">Grouped&nbsp;Classes</font></a>&nbsp;&middot; <a href="modules.html"><font color="#004faf">Modules</font></a>&nbsp;&middot; <a href="functions.html"><font color="#004faf">Functions</font></a></td>
<td align="right" valign="top" width="230"><a href="http://www.trolltech.com"><img src="images/trolltech-logo.png" align="right" width="203" height="32" border="0" /></a></td></tr></table><h1 align="center">QDBusContext Class Reference<br /><sup><sup>[<a href="qtdbus.html">QtDBus</a> module]</sup></sup></h1>
<p>The QDBusContext class allows slots to determine the D-Bus context of the calls. <a href="#details">More...</a></p>
<pre> #include &lt;QDBusContext&gt;</pre><p>This class was introduced in Qt 4.3.</p>
<ul>
<li><a href="qdbuscontext-members.html">List of all members, including inherited members</a></li>
</ul>
<a name="public-functions"></a>
<h3>Public Functions</h3>
<ul>
<li><div class="fn"/><b><a href="qdbuscontext.html#QDBusContext">QDBusContext</a></b> ()</li>
<li><div class="fn"/><b><a href="qdbuscontext.html#dtor.QDBusContext">~QDBusContext</a></b> ()</li>
<li><div class="fn"/>bool <b><a href="qdbuscontext.html#calledFromDBus">calledFromDBus</a></b> () const</li>
<li><div class="fn"/>QDBusConnection <b><a href="qdbuscontext.html#connection">connection</a></b> () const</li>
<li><div class="fn"/>bool <b><a href="qdbuscontext.html#isDelayedReply">isDelayedReply</a></b> () const</li>
<li><div class="fn"/>const QDBusMessage &amp; <b><a href="qdbuscontext.html#message">message</a></b> () const</li>
<li><div class="fn"/>void <b><a href="qdbuscontext.html#sendErrorReply">sendErrorReply</a></b> ( const QString &amp; <i>name</i>, const QString &amp; <i>msg</i> = QString() ) const</li>
<li><div class="fn"/>void <b><a href="qdbuscontext.html#sendErrorReply-2">sendErrorReply</a></b> ( QDBusError::ErrorType <i>type</i>, const QString &amp; <i>msg</i> = QString() ) const</li>
<li><div class="fn"/>void <b><a href="qdbuscontext.html#setDelayedReply">setDelayedReply</a></b> ( bool <i>enable</i> ) const</li>
</ul>
<a name="details"></a>
<hr />
<h2>Detailed Description</h2>
<p>The QDBusContext class allows slots to determine the D-Bus context of the calls.</p>
<p>When a slot is called in an object due to a signal delivery or due to a remote method call, it is sometimes necessary to know the context in which that happened. In particular, if the slot determines that it wants to send the reply at a later opportunity or if it wants to reply with an error, the context is needed.</p>
<p>The QDBusContext class is an alternative to accessing the context that doesn't involve modifying the code generated by the <a href="qdbusxml2cpp.html">QtDBus XML Compiler (qdbusxml2cpp)</a>.</p>
<p>QDBusContext is used by subclassing it from the objects being exported using <a href="qdbusconnection.html#registerObject">QDBusConnection::registerObject</a>(). The following example illustrates the usage:</p>
<pre> class MyObject: public QObject,
                 protected QDBusContext
 {
     Q_OBJECT
     QDBusConnection conn;
     QDBusMessage msg;

 ...

 protected Q_SLOTS:
     void process();
 public Q_SLOTS:
     void methodWithError();
     QString methodWithDelayedReply();
 };

 void MyObject::methodWithError()
 {
     sendErrorReply(QDBusError::NotSupported,
                    &quot;The method call 'methodWithError()' is not supported&quot;);
 }

 QString MyObject::methodWithDelayedReply()
 {
     conn = connection();
     msg = message();
     setDelayedReply(true);
     QMetaObject::invokeMethod(this, &quot;process&quot;, Qt::QueuedConnection);
     return QString();
 }</pre>
<p>The example illustrates the two typical uses, that of sending error replies and that of delayed replies.</p>
<p>Note: do not subclass QDBusContext and <a href="qdbusabstractadaptor.html">QDBusAbstractAdaptor</a> at the same time. QDBusContext should appear in the real object, not the adaptor. If it's necessary from the adaptor code to determine the context, use a public inheritance and access the functions via <a href="qobject.html#parent">QObject::parent</a>().</p>
<hr />
<h2>Member Function Documentation</h2>
<h3 class="fn"><a name="QDBusContext"></a>QDBusContext::QDBusContext ()</h3>
<p>Constructs an empty <a href="qdbuscontext.html">QDBusContext</a>.</p>
<h3 class="fn"><a name="dtor.QDBusContext"></a>QDBusContext::~QDBusContext ()</h3>
<p>An empty destructor.</p>
<h3 class="fn"><a name="calledFromDBus"></a>bool QDBusContext::calledFromDBus () const</h3>
<p>Returns true if we are processing a D-Bus call. If this function returns true, the rest of the functions in this class are available.</p>
<p>Accessing those functions when this function returns false is undefined and may lead to crashes.</p>
<h3 class="fn"><a name="connection"></a><a href="qdbusconnection.html">QDBusConnection</a> QDBusContext::connection () const</h3>
<p>Returns the connection from which this call was received.</p>
<h3 class="fn"><a name="isDelayedReply"></a>bool QDBusContext::isDelayedReply () const</h3>
<p>Returns true if this call will have a delayed reply.</p>
<p>See also <a href="qdbuscontext.html#setDelayedReply">setDelayedReply</a>().</p>
<h3 class="fn"><a name="message"></a>const <a href="qdbusmessage.html">QDBusMessage</a> &amp; QDBusContext::message () const</h3>
<p>Returns the message that generated this call.</p>
<h3 class="fn"><a name="sendErrorReply"></a>void QDBusContext::sendErrorReply ( const <a href="qstring.html">QString</a> &amp; <i>name</i>, const <a href="qstring.html">QString</a> &amp; <i>msg</i> = QString() ) const</h3>
<p>Sends an error <i>name</i> as a reply to the caller. The optional <i>msg</i> parameter is a human-readable text explaining the failure.</p>
<p>If an error is sent, the return value and any output parameters from the called slot will be ignored by <a href="qtdbus.html">QtDBus</a>.</p>
<h3 class="fn"><a name="sendErrorReply-2"></a>void QDBusContext::sendErrorReply ( <a href="qdbuserror.html#ErrorType-enum">QDBusError::ErrorType</a> <i>type</i>, const <a href="qstring.html">QString</a> &amp; <i>msg</i> = QString() ) const</h3>
<p>This is an overloaded member function, provided for convenience.</p>
<p>Sends an error <i>type</i> as a reply to the caller. The optional <i>msg</i> parameter is a human-readable text explaining the failure.</p>
<p>If an error is sent, the return value and any output parameters from the called slot will be ignored by <a href="qtdbus.html">QtDBus</a>.</p>
<h3 class="fn"><a name="setDelayedReply"></a>void QDBusContext::setDelayedReply ( bool <i>enable</i> ) const</h3>
<p>Sets whether this call will have a delayed reply or not.</p>
<p>If <i>enable</i> is false, <a href="qtdbus.html">QtDBus</a> will automatically generate a reply back to the caller, if needed, as soon as the called slot returns.</p>
<p>If <i>enable</i> is true, <a href="qtdbus.html">QtDBus</a> will not generate automatic replies. It will also ignore the return value from the slot and any output parameters. Instead, the called object is responsible for storing the incoming message and send a reply or error at a later time.</p>
<p>Failing to send a reply will result in an automatic timeout error being generated by D-Bus.</p>
<p>See also <a href="qdbuscontext.html#isDelayedReply">isDelayedReply</a>().</p>
<p /><address><hr /><div align="center">
<table width="100%" cellspacing="0" border="0"><tr class="address">
<td width="30%">Copyright &copy; 2008 <a href="trolltech.html">Trolltech</a></td>
<td width="40%" align="center"><a href="trademarks.html">Trademarks</a></td>
<td width="30%" align="right"><div align="right">Qt 4.3.5</div></td>
</tr></table></div></address></body>
</html>
